{"id":13475375,"url":"https://github.com/riverloopsec/killerbee","last_synced_at":"2025-03-27T00:31:18.564Z","repository":{"id":29261435,"uuid":"32794055","full_name":"riverloopsec/killerbee","owner":"riverloopsec","description":"IEEE 802.15.4/ZigBee Security Research Toolkit","archived":false,"fork":false,"pushed_at":"2023-09-12T09:39:25.000Z","size":3237,"stargazers_count":759,"open_issues_count":30,"forks_count":215,"subscribers_count":47,"default_branch":"develop","last_synced_at":"2024-10-31T02:03:37.161Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://www.riverloopsecurity.com","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/riverloopsec.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2015-03-24T11:19:47.000Z","updated_at":"2024-10-28T16:28:46.000Z","dependencies_parsed_at":"2024-01-07T13:04:18.714Z","dependency_job_id":"efc3bfc4-cd84-48e2-9a12-96e93e54e29c","html_url":"https://github.com/riverloopsec/killerbee","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/riverloopsec%2Fkillerbee","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/riverloopsec%2Fkillerbee/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/riverloopsec%2Fkillerbee/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/riverloopsec%2Fkillerbee/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/riverloopsec","download_url":"https://codeload.github.com/riverloopsec/killerbee/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245760687,"owners_count":20667886,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T16:01:19.871Z","updated_at":"2025-03-27T00:31:17.952Z","avatar_url":"https://github.com/riverloopsec.png","language":"C","readme":"KillerBee\n================\n\nKillerBee is a Framework and Tools for Testing \u0026 Auditing ZigBee and IEEE 802.15.4 Networks\n\n\u003e **Notice**\n\u003e * usb0.x support is being deprecated/removed\n\u003e * Apimote v1 support is being deprected/removed\n\u003e\n\u003e If you require these features please create an issue to explain your usecase and requirements.\n\n\u003e **KillerBee 3.0.0-beta Update**\n\u003e \n\u003e Hi everyone, thank you for your continued support and interest in KillerBee.\n\u003e \n\u003e As we are putting new effort into cleaning up the code, migrating to Python 3, adding features, functionality, and consistency, we're using this overhaul as an opportunity to revisit the goals and uses for the project and the best way to accomplish those.\n\u003e \n\u003e This effort will result in a major version update as we deprecate old functions and dependencies \n\u003e and restructure the code to help organize features and enable funcitonality to be extended.\n\u003e \n\u003e This is also an attempt to define the pieces that make up KillerBee, aiming to draw more distinct lines\n\u003e around features in KillerBee and treating it as library.\n\u003e See [ARCHITECTURE.md](ARCHITECTURE.md) for details about this and future goals.\n\nMAINTAINERS/LICENSE\n================\n\nDistributed under a BSD license, see LICENSE.txt for details.\nAll Rights Reserved.\n\nThe main toolkit was/is authored by:\n+ 2009, Joshua Wright \u003cjwright@willhackforsushi.com\u003e\n+ 2010-2019, Ryan Speers \u003cryan@riverloopsecurity.com\u003e\n+ 2010-2011, Ricky Melgares \u003cricky@riverloopsecurity.com\u003e\n\nWe appreciate the many contributers to the framework, including the following who have contributed capabilities:\n+ Anonymous Contributors\n+ Spencer McIntyre (scapy extension)\n+ Bryan Halfpap \u003cBryanhalf@gmail.com\u003e (additional tools)\n+ Travis Goodspeed\n+ Mike Kershaw (dragorn)\n+ Chris Wang (aikiba)\n+ Nick DePetrillo\n+ Ed Skoudis\n+ Matt Carpenter\n+ Sergey Bratus (research support at Dartmouth)\n+ Jeff Spielberg\n+ Scytmo (bug fixes and CC2530/1 EMK board support)\n+ Adam Laurie/rfidiot (APS crypto implementation, firmware, DFU \u0026 BOOTLOADER, SubGHZ, SiLabs NodeTest)\n+ Steve Martin\n+ Taylor Centers \u003ctaylor@riverloopsecurity.com\u003e (Python 3 port)\n+ SecureAB (Python 3)\n+ Jan Rude (Python 3, Sewio)\n+ Damien Cauquil (CC2531 BumbleBee)\n\nREQUIREMENTS\n================\n\nKillerBee is developed and tested on Linux systems.\nMacOS usage is possible but not supported.\n\nWe have striven to use a minimum number of software dependencies, however, it\nis necessary to install the following Python modules before installation.\nThe install will detect and prompt you for what is needed.\n\nOn Ubuntu systems, you can install the needed dependencies with the following\ncommands:\n```\n# apt-get install python-usb python-crypto python-serial python-dev libgcrypt-dev\n```\n\nOn Mac OS, you can install the dependencies with the following commands\n```\n# brew install libusb libgcrypt\n# pip3 install pyusb scapy\n```\n\nThe python-dev and libgcrypt are required for the Scapy Extension Patch.\n\nAlso note that this is a fairly advanced and un-friendly attack platform.  This\nis not Cain \u0026 Abel.  It is intended for developers and advanced analysts who are\nattacking ZigBee and IEEE 802.15.4 networks.  I recommend you gain some\nunderstanding of the ZigBee protocol (the book [ZigBee Wireless Networks and\nTransceivers by Shahin Farahani](http://bit.ly/2I5ppI) is reasonable, though\nstill not great) and familiarity with the Python language before digging into\nthis framework.\n\n\nINSTALLATION\n================\nKillerBee uses the standard Python 'setup.py' installation file, once dependencies are installed.\n\nInstall KillerBee with the following command:\n```\n# python3 setup.py install\n```\n\nDIRECTORIES\n================\nThe directory structure for the KillerBee code is described as follows:\n\n+ doc       - HTML documentation on the KillerBee library, courtesy of epydoc.\n+ firmware  - Firmware for supported KillerBee hardware devices.\n+ killerbee - Python library source.\n+ sample    - Sample packet captures, referenced below.\n+ scripts   - Shell scripts used in development.\n+ tools     - ZigBee and IEEE 802.15.4 attack tools developed using this framework.\n\nREQUIRED HARDWARE\n================\nThe KillerBee framework is being expanded to support multiple devices.\nCurrently there is support for the River Loop ApiMote, Atmel RZ RAVEN USB Stick,\nMoteIV Tmote Sky, TelosB mote, Sewino Sniffer, and various hardware running Silicon Labs Node Test firmware.\n\n**See [firmware/README.md](firmware/README.md) for details on hardware support and firmware programming.**\n\nSupport for Freaklab's Freakduino with added hardware \u0026 the Dartmouth arduino sketch\nand Zigduino boards are available but are not listed as they are not maintained.\nYou must enable these to be searched for in `killerbee/config.py` and then reinstall KillerBee.\n\nTOOLS\n================\nKillerBee includes several tools designed to attack ZigBee and IEEE 802.15.4\nnetworks, built using the KillerBee framework.  Each tool has its own usage\ninstructions documented by running the tool with the \"-h\" argument, and\nsummarized below.\n\n+ zbid         -  Identifies available interfaces that can be used by KillerBee\n                and associated tools.\n+ zbwireshark  -  Similar to zbdump but exposes a named pipe for real-time \n                capture and viewing in Wireshark.\n+ zbdump       -  A tcpdump-like took to capture IEEE 802.15.4 frames to a libpcap\n                or Daintree SNA packet capture file.  Does not display real-time\n                stats like tcpdump when not writing to a file.\n+ zbreplay     -  Implements a replay attack, reading from a specified Daintree\n                DCF or libpcap packet capture file, retransmitting the frames.\n                ACK frames are not retransmitted.\n+ zbstumbler   -  Active ZigBee and IEEE 802.15.4 network discovery tool.\n                Zbstumbler sends beacon request frames out while channel\n                hopping, recording and displaying summarized information about\n                discovered devices.  Can also log results to a CSV file.\n+ zbpanidconflictflood  -  _Requires two killerbee interfaces_ one killerbee interface\n                listens for packets and marks their PAN ID.  The other interface\n                constantly sends out beacon packets with found PAN ID's.  The\n                beacon packets with the same PAN ID cause the PAN coordinator to\n                believe that there is a PAN ID conflict, and the coordinator begins\n                the process of realigning the network on a new PAN ID.  The process\n                repeats ad nauseum.  Typically, network devices can't keep up with\n                the rapid change and after several seconds the network falls apart.\n                _NO TARGETING BUILT IN: This may *destroy* all zigbee networks\n                within range on the channel you are performing the attack on. Use\n                with caution._\n+ zborphannotify  -  Spoofs an orphan notification packet from the target device to\n                a PAN Coordinator to test Coordinator behavior.\n+ zbrealign     -  Spoofs an 802.15.4 PAN Realignment frame from the coordinator to\n                a target device.  May be able to reset the device's PAN ID or Channel\n+ zbfakebeacon  -  Spoofs beacon frames, either spamming them or on response to seeing\n                a beacon request come through.\n+ zbopenear    -  Assists in data capture where devices are operating on multiple \n                channels or fast-frequency-hopping. It assigns multiple \n                interfaces sequentially across all channels.\n+ zbassocflood -  Repeatedly associate to the target PANID in an effort to cause\n                the device to crash from too many connected stations.\n+ zbconvert    -  Convert a packet capture from Libpcap to Daintree SNA format,\n                or vice-versa.\n+ zbdsniff     -  Captures ZigBee traffic, looking for NWK frames and over-the-air\n                key provisioning.  When a key is found, zbdsniff prints the\n                key to stdout.  The sample packet capture\n                `sample/zigbee-network-key-ota.dcf` can be used to demonstrate\n                this functionality.\n+ zbfind       -  A GTK GUI application for tracking the location of an IEEE\n                802.15.4 transmitter by measuring RSSI. zbfind can be passive\n                in discovery (only listen for packets) or it can be active by\n                sending Beacon Request frames and recording the responses from\n                ZigBee routers and coordinators.\n                If you get a bunch of errors after starting this tool, make\n                sure your `DISPLAY` variable is set properly.\n+ zbgoodfind   -  Implements a key search function using an encrypted packet\n                capture and memory dump from a legitimate ZigBee or IEEE\n                802.15.4 device.  This tool accompanies Travis Goodspeed's\n                GoodFET hardware attack tool, or other binary data that could\n                contain encryption key information such as bus sniffing with\n                legacy chips (such as the CC2420).  Zbgoodfind's search file\n                must be in binary format (obj hexfile's are not supported). To\n                convert from the hexfile format to a binary file, use the\n                objcopy tool: objcopy -I ihex -O binary mem.hex mem.bin\n+ zbwardrive   -\tDiscovers available interfaces and uses one to inject beacon \n                requests and listen for respones across channels. Once a network\n                is found on a channel, it assigns another device to continuously\n                capture traffic on that channel to a PCAP file. Scapy must be \n                installed to run this.\n+ zbscapy      -  Provides an interactive Scapy shell for interacting via a\n                KillerBee interface. Scapy must be installed to run this.\n+ kbbootloader -  Switches device into DFU/BOOTLOADER mode (if device is capable)\n\nAdditional tools, that are for special cases or are not stable, are stored in\n    the Api-Do project repository: http://code.google.com/p/zigbee-security/\n    and at https://github.com/riverloopsec/beekeeperwids.\n\n\nFRAMEWORK\n==============\nKillerBee is designed to simplify the process of sniffing packets from the air\ninterface or a supported packet capture file (libpcap), and for\ninjecting arbitrary packets.  Helper functions including IEEE 802.15.4, ZigBee\nNWK and ZigBee APS packet decoders are available as well.\n\nThe KillerBee API is documented in epydoc format, with HTML documentation in \nthe `doc/` directory of this distribution.  If you have epydoc installed, you can\nalso generate a convenient PDF for printing, if desired, as shown:\n\n```\n$ cd killerbee\n$ mkdir pdf\n$ epydoc --pdf -o pdf killerbee/\n```\n\nThe pdf/ directory will have a file called \"api.pdf\" which includes the\nframework documentation.\n\nTo get started using the KillerBee framework, take a look at the included tools\n(zbdump and zbreplay are good examples to get started).\n\nSince KillerBee is a Python library, it integrates well with other Python\nsoftware as well.  For example, the Sulley library is a fuzzing framework\nwritten in Python by Pedram Amini.  Using the Sulley mutation features and\nKillerBee's packet injection features, it is staightforward to build a\nmechanism for generating and transmitting malformed ZigBee data to a target.\n\n\nQUESTIONS/COMMENTS/CONCERNS\n==============\nPlease use the ticketing system at https://github.com/riverloopsec/killerbee/issues.\n\nThe original version was written by: jwright@willhackforsushi.com.\nThe current version, fixes, etc are handled by: killerbee@riverloopsecurity.com.\n(See the list above for all contributors/credits.)\n\nFor contributors/developers, see [`DEVELOPMENT.md`](DEVELOPMENT.md) for details and guidance.\n","funding_links":[],"categories":["Uncategorized","C","ZigBee","Tools","Misc RF Tools","Wireless Protocols","Software Tools"],"sub_categories":["Uncategorized","Tools","Telemetry Detection \u0026 Eavesdropping Tools","Zigbee / Z-Wave","Analysis Frameworks"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Friverloopsec%2Fkillerbee","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Friverloopsec%2Fkillerbee","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Friverloopsec%2Fkillerbee/lists"}