Skip to content

Commit

Permalink
Merge pull request #204 from riverloopsec/py3
Browse files Browse the repository at this point in the history
Py3
taylorcenters authored Mar 30, 2021
2 parents d38be5f + 4cc4674 commit b7dd750
Showing 75 changed files with 2,516 additions and 1,030 deletions.
33 changes: 33 additions & 0 deletions ARCHITECTURE.md
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)
2 changes: 1 addition & 1 deletion DEVELOPMENT.md
Original file line number Diff line number Diff line change
@@ -7,7 +7,7 @@ We welcome and greatly appreciate improvements and contributions!
Python Versions
================

Please write all code to be compatible with Python 2.7+ and 3.5+.
Please write all code to be compatible with Python 3.5+.

Branching
================
2 changes: 1 addition & 1 deletion FAQ.md
Original file line number Diff line number Diff line change
@@ -46,7 +46,7 @@ Install the requirement, such as `sudo apt-get install -y libgcrypt-dev`.

#### Flashing

See `firmware/README.md` for details.
See [firmware/README.md](firmware/README.md) for details.

#### ValueError device has no langid

114 changes: 30 additions & 84 deletions README.md
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.
78 changes: 68 additions & 10 deletions firmware/README.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,14 @@
Firmware
================
# Supported Devices & Firmware

ApiMote
==================

## ApiMote v4beta

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 online from resellers, or at cost for bulk orders by contacting team at riverloopsecurity dot com.

_This is currently supported for beta, and supports sniffing, injection, and jamming._

The firmware for this is mainained and built using the GoodFET repository.

@@ -11,25 +17,77 @@ Compiled firmware versions are stored here for ease of use. However, you should
To flash it, plug in the ApiMote v3 or v4beta and then run the `flash\_apimote.sh` script.
Note that it may sometimes take two attempts to flash correctly if the first time doesn't synchronize and times out.

Silicon Labs Node Test 2.4GHz & SubGHz:
==================
See https://www.silabs.com/documents/public/application-notes/AN1019-NodeTest.pdf

## 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._


## Silicon Labs Node Test 2.4GHz & SubGHz

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)

You must enable these to be searched for in `killerbee/config.py` and then reinstall KillerBee.

_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_

See https://www.silabs.com/documents/public/application-notes/AN1019-NodeTest.pdf

It can be installed in Simplicity Studio by right clicking on the device in the 'Debug Adapters' window and selecting the appropriate Nodetest image for your hardware from the 'Upload application' menu (note that some of them are misspelled as 'Notetest').

The device should come up as a CDC Serial port and can be addressed with the '-i' flag. For example, to sniff on Channel 0, SubGHz Page 28:
```
zbwireshark -c 0 -s 28 -i /dev/ttyACM0
```

_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_

RZUSBSTICK
==================
## MoteIV Tmote Sky or TelosB mote

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 USBSTICK (RZUSBSTICK)

> NOTE: Atmel has stopped selling this hardware.
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 this `firmware/ `
directory.

This needs to be flashed using external tools. Compiled firmware is:
- `kb-rzusbstick-001.hex`: Initial version
Loading

0 comments on commit b7dd750

Please sign in to comment.