Skip to content

Commit b7dd750

Browse files
taylorcenterstaylorcenters
authored
Merge pull request #204 from riverloopsec/py3
Py3
2 parents d38be5f + 4cc4674 commit b7dd750

75 files changed

Lines changed: 2516 additions & 1030 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎ARCHITECTURE.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# Architecture
2+
3+
## Overview
4+
5+
The below table is intended to help orient users to the different parts of the KillerBee codebase,
6+
and share overall thoughts for planned future changes to allow for comments, feedback, and planning.
7+
8+
| Category | Sub-category | Description | Examples | Notes |
9+
| -------- | ------------ | ----------- | -------- | ----- |
10+
| core | | The library that is used to interact with the radio peripheral | `pnext()`, `inject()`, `set_channel()`, `sniffer_on()/off()` | |
11+
| | drivers | Device specific implementation of "core" functionality | `dev_*.py` | Will be moved to a sub-directory. |
12+
| utilities | | Convenience functions for working with ZigBee | | |
13+
| | pcap | | | Plan to migrate to using scapy fully for this |
14+
| | device | | `devlist()`, `is_\[device\]()` | Possibly move this into core |
15+
| | zigbee | | `makeFCS()`, `randmac()`, `extractkey()` | |
16+
| | crypto | | `encrypt_ccm()`, `decrypt_ccm()`, `hash_mmo()` | |
17+
| | rf4ce | | `derivekey()` | Planned future features. |
18+
| | home-automation | | `disarm()`, `sensor_trigger()`, `tamper()` | Planned future features. |
19+
| scapy-extension | | A wrapper around "core" and "utility" for convenience when working alongside scapy or as-if working with scapy | `kbsend()`, `kbsniff()` | |
20+
| | home-automation layer | | | Planned future features. |
21+
| tools | simple | Simple script wrappers around "core" or "utility" functionality | e.g., `zbcat`, `zbdump`, `zbwireshark`, `zbid`, `zbcrypto` | |
22+
| | fully-featured | Other, more complex tools | `zbwardrive`, `openear` | These will be promoted to their own repository |
23+
24+
## Additional Goals
25+
26+
* Migrate remaining tools and utilities to use Dot15d4 Scapy for packet construction
27+
* Move device configuration to runtime options rather than "compile" time
28+
* Add unittesting coverage (see `tests/` for coverage so far)
29+
* Add pytypes
30+
* Move documentation to modern framework such as Sphinx
31+
* Publish documentation to [readthedocs.io](https://readthedocs.io)
32+
* Publish KillerBee to pypi to simplify installation
33+
* Have KillerBee updated in distros (e.g., Kali)

‎DEVELOPMENT.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ We welcome and greatly appreciate improvements and contributions!
77
Python Versions
88
================
99

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

1212
Branching
1313
================

‎FAQ.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,7 @@ Install the requirement, such as `sudo apt-get install -y libgcrypt-dev`.
4646

4747
#### Flashing
4848

49-
See `firmware/README.md` for details.
49+
See [firmware/README.md](firmware/README.md) for details.
5050

5151
#### ValueError device has no langid
5252

‎README.md‎

Lines changed: 30 additions & 84 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,20 @@ KillerBee
33

44
KillerBee is a Framework and Tools for Testing & Auditing ZigBee and IEEE 802.15.4 Networks
55

6+
> **KillerBee 3.0.0-beta Update**
7+
>
8+
> Hi everyone, thank you for your continued support and interest in KillerBee.
9+
>
10+
> 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.
11+
>
12+
> This effort will result in a major version update as we deprecate old functions and dependencies
13+
> and restructure the code to help organize features and enable funcitonality to be extended.
14+
>
15+
> This is also an attempt to define the pieces that make up KillerBee, aiming to draw more distinct lines
16+
> around features in KillerBee and treating it as library.
17+
> See [ARCHITECTURE.md](ARCHITECTURE.md) for details about this and future goals.
18+
19+
620
MAINTAINERS/LICENSE
721
================
822

@@ -29,6 +43,10 @@ We appreciate the many contributers to the framework, including the following wh
2943
+ Scytmo (bug fixes and CC2530/1 EMK board support)
3044
+ Adam Laurie/rfidiot (APS crypto implementation, firmware, DFU & BOOTLOADER, SubGHZ, SiLabs NodeTest)
3145
+ Steve Martin
46+
+ Taylor Centers <taylor@riverloopsecurity.com> (Python 3 port)
47+
+ SecureAB (Python 3)
48+
+ Jan Rude (Python 3, Sewio)
49+
+ Damien Cauquil (CC2531 BumbleBee)
3250

3351
REQUIREMENTS
3452
================
@@ -42,12 +60,9 @@ The install will detect and prompt you for what is needed.
4260

4361
On Ubuntu systems, you can install the needed dependencies with the following
4462
commands:
45-
4663
```
4764
# apt-get install python-gtk2 python-cairo python-usb python-crypto python-serial python-dev libgcrypt-dev
48-
# git clone https://github.com/secdev/scapy
49-
# cd scapy
50-
# python setup.py install
65+
# python3 setup.py install
5166
```
5267

5368
The python-dev and libgcrypt are required for the Scapy Extension Patch.
@@ -63,9 +78,9 @@ this framework.
6378

6479
INSTALLATION
6580
================
66-
KillerBee uses the standard Python 'setup.py' installation file.
67-
Install KillerBee with the following command:
81+
KillerBee uses the standard Python 'setup.py' installation file, once dependencies are installed.
6882

83+
Install KillerBee with the following command:
6984
```
7085
# python setup.py install
7186
```
@@ -87,79 +102,11 @@ The KillerBee framework is being expanded to support multiple devices.
87102
Currently there is support for the River Loop ApiMote, Atmel RZ RAVEN USB Stick,
88103
MoteIV Tmote Sky, TelosB mote, Sewino Sniffer, and various hardware running Silicon Labs Node Test firmware.
89104

90-
Support for Freaklab's Freakduino with added hardware & the Dartmouth arduino sketch
91-
and Zigduino boards are available but are not listed below as they are not maintained.
92-
You must enable these to be searched for in `killerbee/config.py` and then reinstall KillerBee.
93-
94-
ApiMote v4beta (and v3):
95-
----------------
96-
The devices typically come preloaded and do not need to be reflashed for basic use.
97-
98-
The hardware is open-source at https://github.com/riverloopsec/apimote.
99-
It is available assembled by contacting team at riverloopsecurity dot com.
100-
101-
_This is currently supported for beta, and supports sniffing, injection, and jamming._
102-
103-
Texas Instruments CC2530/1 EMK:
104-
----------------
105-
106-
This USB dongle is produced by Texas Instruments and is sold as an evaluation
107-
kit for their CC2530 or CC2531 integrated circuit.
108-
109-
It can be purchased from electronics distributors, or directly from them
110-
[here](http://www.ti.com/tool/cc2531emk).
111-
112-
_This is currently supported for beta, and supports sniffing only._
113-
114-
MoteIV Tmote Sky or TelosB mode:
115-
----------------
116-
This device can be loaded with firmware via USB. Attach the device, and then
117-
within killerbee/firmware, run:
118-
```
119-
$ ./flash_telosb.sh
120-
```
121-
122-
These boards can be obtained via multiple distributors, however
123-
[this vendor](https://www.advanticsys.com/shop/mtmcm5000msp-p-14.html) has
124-
stated that their "clone" of the original hardware is compatible.
125-
We have not tested nor do we endorse any specific "clone".
126-
127-
Atmel RZ RAVEN USB Stick:
128-
----------------
129-
See http://www.atmel.com/tools/RZUSBSTICK.aspx.
130-
This hardware
131-
is convenient as the base firmware is open source with a freely-available IDE.
132-
The KillerBee firmware for the RZ RAVEN included in the `firmware/` directory is
133-
a modified version of the stock firmware distributed by Atmel to include
134-
attack functionality.
135-
136-
The RZ RAVEN USB Stick is available from common electronics resellers for
137-
approximately $40/USD:
138-
139-
+ Mouser: http://bit.ly/vZ2pt
140-
+ Digi-Key: http://bit.ly/3T8MaK
141-
142-
The stock firmware shipped with this hardware allows you to leverage the passive
143-
functionality included in the KillerBee tools and framework (such as receiving
144-
frames), but does not allow you to do packet injection, or to impersonate
145-
devices on the network.
146-
147-
In order to get the full functionality included in KillerBee, the RZ RAVEN USB
148-
Stick must be flashed with the custom firmware included in the `firmware/ `
149-
directory. _See [firmware/README.md](firmware/README.md) for details._
150-
151-
Silicon Labs Node Test 2.4GHz & SubGHz:
152-
----------------
153-
See [SiLabs AN1019](https://www.silabs.com/documents/public/application-notes/AN1019-NodeTest.pdf).
154-
155-
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:
156-
+ 2.4 GHz (ch 11-26)
157-
+ 863-917 MHz (pages 28-31, ch 0-26)
105+
**See [firmware/README.md](firmware/README.md) for details on hardware support and firmware programming.**
158106

107+
Support for Freaklab's Freakduino with added hardware & the Dartmouth arduino sketch
108+
and Zigduino boards are available but are not listed as they are not maintained.
159109
You must enable these to be searched for in `killerbee/config.py` and then reinstall KillerBee.
160-
See [firmware/README.md](firmware/README.md) for installation details.
161-
162-
_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_
163110

164111
TOOLS
165112
================
@@ -190,10 +137,9 @@ summarized below.
190137
the process of realigning the network on a new PAN ID. The process
191138
repeats ad nauseum. Typically, network devices can't keep up with
192139
the rapid change and after several seconds the network falls apart.
193-
194-
_NO TARGETING BUILT IN_ This may *destroy* all zigbee networks
140+
_NO TARGETING BUILT IN: This may *destroy* all zigbee networks
195141
within range on the channel you are performing the attack on. Use
196-
with caution.
142+
with caution._
197143
+ zborphannotify - Spoofs an orphan notification packet from the target device to
198144
a PAN Coordinator to test Coordinator behavior.
199145
+ 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
245191
FRAMEWORK
246192
==============
247193
KillerBee is designed to simplify the process of sniffing packets from the air
248-
interface or a supported packet capture file (libpcap or Daintree SNA), and for
194+
interface or a supported packet capture file (libpcap), and for
249195
injecting arbitrary packets. Helper functions including IEEE 802.15.4, ZigBee
250196
NWK and ZigBee APS packet decoders are available as well.
251197

252198
The KillerBee API is documented in epydoc format, with HTML documentation in
253-
the doc/ directory of this distribution. If you have epydoc installed, you can
199+
the `doc/` directory of this distribution. If you have epydoc installed, you can
254200
also generate a convenient PDF for printing, if desired, as shown:
255201

256202
```
@@ -277,7 +223,7 @@ QUESTIONS/COMMENTS/CONCERNS
277223
Please use the ticketing system at https://github.com/riverloopsec/killerbee/issues.
278224

279225
The original version was written by: jwright@willhackforsushi.com.
280-
The current version, fixes, etc are handled by: ryan@riverloopsecurity.com.
226+
The current version, fixes, etc are handled by: killerbee@riverloopsecurity.com.
281227
(See the list above for all contributors/credits.)
282228

283-
For contributors/developers, see `DEVELOPMENT.md` for details and guidance.
229+
For contributors/developers, see [`DEVELOPMENT.md`](DEVELOPMENT.md) for details and guidance.

‎firmware/README.md‎

Lines changed: 68 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,14 @@
1-
Firmware
2-
================
1+
# Supported Devices & Firmware
32

4-
ApiMote
5-
==================
3+
4+
## ApiMote v4beta
5+
6+
The devices typically come preloaded and do not need to be reflashed for basic use.
7+
8+
The hardware is open-source at https://github.com/riverloopsec/apimote.
9+
It is available assembled online from resellers, or at cost for bulk orders by contacting team at riverloopsecurity dot com.
10+
11+
_This is currently supported for beta, and supports sniffing, injection, and jamming._
612

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

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

14-
Silicon Labs Node Test 2.4GHz & SubGHz:
15-
==================
16-
See https://www.silabs.com/documents/public/application-notes/AN1019-NodeTest.pdf
20+
21+
## Texas Instruments CC2530/1 EMK
22+
23+
This USB dongle is produced by Texas Instruments and is sold as an evaluation
24+
kit for their CC2530 or CC2531 integrated circuit.
25+
26+
It can be purchased from electronics distributors, or directly from them
27+
[here](http://www.ti.com/tool/cc2531emk).
28+
29+
_This is currently supported for beta, and supports sniffing only._
30+
31+
32+
## Silicon Labs Node Test 2.4GHz & SubGHz
1733

1834
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:
1935
+ 2.4 GHz (ch 11-26)
2036
+ 863-917 MHz (pages 28-31, ch 0-26)
2137

38+
You must enable these to be searched for in `killerbee/config.py` and then reinstall KillerBee.
39+
40+
_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_
41+
42+
See https://www.silabs.com/documents/public/application-notes/AN1019-NodeTest.pdf
43+
2244
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').
2345

2446
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:
2547
```
2648
zbwireshark -c 0 -s 28 -i /dev/ttyACM0
2749
```
2850

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

31-
RZUSBSTICK
32-
==================
52+
## MoteIV Tmote Sky or TelosB mote
53+
54+
This device can be loaded with firmware via USB. Attach the device, and then
55+
within killerbee/firmware, run:
56+
```
57+
$ ./flash_telosb.sh
58+
```
59+
60+
These boards can be obtained via multiple distributors, however
61+
[this vendor](https://www.advanticsys.com/shop/mtmcm5000msp-p-14.html) has
62+
stated that their "clone" of the original hardware is compatible.
63+
We have not tested nor do we endorse any specific "clone".
64+
65+
66+
## Atmel RZ Raven USBSTICK (RZUSBSTICK)
67+
68+
> NOTE: Atmel has stopped selling this hardware.
69+
70+
See http://www.atmel.com/tools/RZUSBSTICK.aspx.
71+
This hardware
72+
is convenient as the base firmware is open source with a freely-available IDE.
73+
The KillerBee firmware for the RZ RAVEN included in the `firmware/` directory is
74+
a modified version of the stock firmware distributed by Atmel to include
75+
attack functionality.
76+
77+
The RZ RAVEN USB Stick is available from common electronics resellers for
78+
approximately $40/USD:
79+
80+
+ Mouser: http://bit.ly/vZ2pt
81+
+ Digi-Key: http://bit.ly/3T8MaK
82+
83+
The stock firmware shipped with this hardware allows you to leverage the passive
84+
functionality included in the KillerBee tools and framework (such as receiving
85+
frames), but does not allow you to do packet injection, or to impersonate
86+
devices on the network.
87+
88+
In order to get the full functionality included in KillerBee, the RZ RAVEN USB
89+
Stick must be flashed with the custom firmware included in this `firmware/ `
90+
directory.
3391

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

0 commit comments

Comments
 (0)