-
Notifications
You must be signed in to change notification settings - Fork 216
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #204 from riverloopsec/py3
Py3
Showing
75 changed files
with
2,516 additions
and
1,030 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,33 @@ | ||
# Architecture | ||
|
||
## Overview | ||
|
||
The below table is intended to help orient users to the different parts of the KillerBee codebase, | ||
and share overall thoughts for planned future changes to allow for comments, feedback, and planning. | ||
|
||
| Category | Sub-category | Description | Examples | Notes | | ||
| -------- | ------------ | ----------- | -------- | ----- | | ||
| core | | The library that is used to interact with the radio peripheral | `pnext()`, `inject()`, `set_channel()`, `sniffer_on()/off()` | | | ||
| | drivers | Device specific implementation of "core" functionality | `dev_*.py` | Will be moved to a sub-directory. | | ||
| utilities | | Convenience functions for working with ZigBee | | | | ||
| | pcap | | | Plan to migrate to using scapy fully for this | | ||
| | device | | `devlist()`, `is_\[device\]()` | Possibly move this into core | | ||
| | zigbee | | `makeFCS()`, `randmac()`, `extractkey()` | | | ||
| | crypto | | `encrypt_ccm()`, `decrypt_ccm()`, `hash_mmo()` | | | ||
| | rf4ce | | `derivekey()` | Planned future features. | | ||
| | home-automation | | `disarm()`, `sensor_trigger()`, `tamper()` | Planned future features. | | ||
| scapy-extension | | A wrapper around "core" and "utility" for convenience when working alongside scapy or as-if working with scapy | `kbsend()`, `kbsniff()` | | | ||
| | home-automation layer | | | Planned future features. | | ||
| tools | simple | Simple script wrappers around "core" or "utility" functionality | e.g., `zbcat`, `zbdump`, `zbwireshark`, `zbid`, `zbcrypto` | | | ||
| | fully-featured | Other, more complex tools | `zbwardrive`, `openear` | These will be promoted to their own repository | | ||
|
||
## Additional Goals | ||
|
||
* Migrate remaining tools and utilities to use Dot15d4 Scapy for packet construction | ||
* Move device configuration to runtime options rather than "compile" time | ||
* Add unittesting coverage (see `tests/` for coverage so far) | ||
* Add pytypes | ||
* Move documentation to modern framework such as Sphinx | ||
* Publish documentation to [readthedocs.io](https://readthedocs.io) | ||
* Publish KillerBee to pypi to simplify installation | ||
* Have KillerBee updated in distros (e.g., Kali) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -3,6 +3,20 @@ KillerBee | |
|
||
KillerBee is a Framework and Tools for Testing & Auditing ZigBee and IEEE 802.15.4 Networks | ||
|
||
> **KillerBee 3.0.0-beta Update** | ||
> | ||
> Hi everyone, thank you for your continued support and interest in KillerBee. | ||
> | ||
> 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. | ||
> | ||
> This effort will result in a major version update as we deprecate old functions and dependencies | ||
> and restructure the code to help organize features and enable funcitonality to be extended. | ||
> | ||
> This is also an attempt to define the pieces that make up KillerBee, aiming to draw more distinct lines | ||
> around features in KillerBee and treating it as library. | ||
> See [ARCHITECTURE.md](ARCHITECTURE.md) for details about this and future goals. | ||
|
||
MAINTAINERS/LICENSE | ||
================ | ||
|
||
|
@@ -29,6 +43,10 @@ We appreciate the many contributers to the framework, including the following wh | |
+ Scytmo (bug fixes and CC2530/1 EMK board support) | ||
+ Adam Laurie/rfidiot (APS crypto implementation, firmware, DFU & BOOTLOADER, SubGHZ, SiLabs NodeTest) | ||
+ Steve Martin | ||
+ Taylor Centers <[email protected]> (Python 3 port) | ||
+ SecureAB (Python 3) | ||
+ Jan Rude (Python 3, Sewio) | ||
+ Damien Cauquil (CC2531 BumbleBee) | ||
|
||
REQUIREMENTS | ||
================ | ||
|
@@ -42,12 +60,9 @@ The install will detect and prompt you for what is needed. | |
|
||
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 | ||
# python3 setup.py install | ||
``` | ||
|
||
The python-dev and libgcrypt are required for the Scapy Extension Patch. | ||
|
@@ -63,9 +78,9 @@ this framework. | |
|
||
INSTALLATION | ||
================ | ||
KillerBee uses the standard Python 'setup.py' installation file. | ||
Install KillerBee with the following command: | ||
KillerBee uses the standard Python 'setup.py' installation file, once dependencies are installed. | ||
|
||
Install KillerBee with the following command: | ||
``` | ||
# python setup.py install | ||
``` | ||
|
@@ -87,79 +102,11 @@ The 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, Sewino Sniffer, and various hardware running Silicon Labs Node Test firmware. | ||
|
||
Support for Freaklab's Freakduino with added hardware & the Dartmouth arduino sketch | ||
and Zigduino boards are available but are not listed below as they are not maintained. | ||
You must enable these to be searched for in `killerbee/config.py` and then reinstall KillerBee. | ||
|
||
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](http://www.ti.com/tool/cc2531emk). | ||
|
||
_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](https://www.advanticsys.com/shop/mtmcm5000msp-p-14.html) 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: | ||
|
||
+ Mouser: http://bit.ly/vZ2pt | ||
+ Digi-Key: http://bit.ly/3T8MaK | ||
|
||
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](firmware/README.md) for details._ | ||
|
||
Silicon Labs Node Test 2.4GHz & SubGHz: | ||
---------------- | ||
See [SiLabs AN1019](https://www.silabs.com/documents/public/application-notes/AN1019-NodeTest.pdf). | ||
|
||
This is a firmware image for a huge variety of hardware platforms, supporting EM250, EM375, EFR32, etc., and provides for (with appropriate radio part) the following frequencies: | ||
+ 2.4 GHz (ch 11-26) | ||
+ 863-917 MHz (pages 28-31, ch 0-26) | ||
**See [firmware/README.md](firmware/README.md) for details on hardware support and firmware programming.** | ||
|
||
Support for Freaklab's Freakduino with added hardware & the Dartmouth arduino sketch | ||
and Zigduino boards are available but are not listed as they are not maintained. | ||
You must enable these to be searched for in `killerbee/config.py` and then reinstall KillerBee. | ||
See [firmware/README.md](firmware/README.md) for installation details. | ||
|
||
_NOTE: This is a SNIFFER only implementation which will only read packets with a good FCS, and although the firmware has injection capability, it adds a 2 byte counter to the end of every packet, rendering it useless for all practical purposes. If you are interested in an INJECTION and BAD FCS capable device, contact the author, Adam Laurie - adam at algroup.co.uk_ | ||
|
||
TOOLS | ||
================ | ||
|
@@ -190,10 +137,9 @@ summarized below. | |
the process of realigning the network on a new PAN ID. The process | ||
repeats ad nauseum. Typically, network devices can't keep up with | ||
the rapid change and after several seconds the network falls apart. | ||
|
||
_NO TARGETING BUILT IN_ This may *destroy* all zigbee networks | ||
_NO TARGETING BUILT IN: This may *destroy* all zigbee networks | ||
within range on the channel you are performing the attack on. Use | ||
with caution. | ||
with caution._ | ||
+ zborphannotify - Spoofs an orphan notification packet from the target device to | ||
a PAN Coordinator to test Coordinator behavior. | ||
+ zbrealign - Spoofs an 802.15.4 PAN Realignment frame from the coordinator to | ||
|
@@ -245,12 +191,12 @@ Additional tools, that are for special cases or are not stable, are stored in | |
FRAMEWORK | ||
============== | ||
KillerBee 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 | ||
interface or a supported packet capture file (libpcap), 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 | ||
the `doc/` directory of this distribution. If you have epydoc installed, you can | ||
also generate a convenient PDF for printing, if desired, as shown: | ||
|
||
``` | ||
|
@@ -277,7 +223,7 @@ QUESTIONS/COMMENTS/CONCERNS | |
Please use the ticketing system at https://github.com/riverloopsec/killerbee/issues. | ||
|
||
The original version was written by: [email protected]. | ||
The current version, fixes, etc are handled by: ryan@riverloopsecurity.com. | ||
The current version, fixes, etc are handled by: killerbee@riverloopsecurity.com. | ||
(See the list above for all contributors/credits.) | ||
|
||
For contributors/developers, see `DEVELOPMENT.md` for details and guidance. | ||
For contributors/developers, see [`DEVELOPMENT.md`](DEVELOPMENT.md) for details and guidance. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.